home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Add-Ons / MPW / MPW rman 1.3.4 / rman.1 < prev    next >
Encoding:
Text File  |  1995-11-08  |  7.8 KB  |  195 lines  |  [TEXT/MPS ]
  1. .TH RosettaMan 1
  2. .SH "NAME "
  3. RosettaMan, rman - reverse compile man pages from formatted form 
  4. to a number of source formats 
  5. .SH "SYNOPSIS "
  6. rman [options] [file] 
  7. .SH "DESCRIPTION "
  8. \fIRosettaMan \fR takes formatted man pages from most of the 
  9. popular flavors of UNIX and transforms them into any of a number 
  10. of text source formats. \fIRosettaMan \fR accepts formatted man 
  11. pages from: Hewlett-Packard HP-UX, AT System V, SunOS, Sun Solaris, 
  12. OSF/1, DEC Ultrix, SGI IRIX, Linux. It can produce ASCII-only, 
  13. section headers-only, TkMan, [tn]roff, Ensemble, SGML, HTML, 
  14. LaTeX, RTF, Perl 5 POD. A modular architecture permits easy addition 
  15. of additional output formats. 
  16. .SH "OPTIONS "
  17. .TP 15
  18. -f <ASCII|roff|TkMan|Ensemble|Sections|HTML|SGML|LaTeX|RTF|POD> 
  19. Set the output filter. Defaults to ASCII. 
  20. .TP 15
  21. -b 
  22. Try to recognize subsection titles in addition to section titles. 
  23. This can cause problems on some UNIX systems. 
  24. .TP 15
  25. -t \fI# \fR
  26. For those macros sets that use tabs in place of spaces where 
  27. possible in order to reduce the number of characters used, set 
  28. tabstops every # columns. Defaults to 8. 
  29. .TP 15
  30. -c 
  31. Move changebars, such as those found in the Tcl/Tk manual pages, 
  32. to the left. 
  33. .TP 15
  34. -m 
  35. \fIDisable \fR aggressive man page parsing. Aggressive manual, 
  36. which is on by default, page parsing elides headers and footers, 
  37. identifies sections and more. 
  38. .TP 15
  39. -v 
  40. Show version number and exit. 
  41. .TP 15
  42. -n \fIname \fR
  43. Set name of man page (used in roff format). If the filename is 
  44. given in the form " \fIname \fR. \fIsection \fR", the name and 
  45. section are automatically determined. 
  46. .TP 15
  47. -s \fI# \fR
  48. Set volume (aka section) number of man page (used in roff format). 
  49. .TP 15
  50. -p 
  51. paragraph mode toggle. The filter determines whether lines should 
  52. be linebroken as they were by nroff, or whether lines should 
  53. be flowed together into paragraphs. Mainly for internal use. 
  54. .TP 15
  55. -r \fIprintf-string \fR
  56. In HTML mode this sets the URL form by which to retrieve other 
  57. man pages. The string can use two supplied parameters: the man 
  58. page name and its section. (See the Examples section.) 
  59. .TP 15
  60. -l \fIprintf-string \fR
  61. In HTML mode this sets the <TITLE> of the man pages, given the 
  62. same parameters as \fI-r \fR. 
  63. .TP 15
  64. -K 
  65. Indicate manual pages don't have page breaks, so don't look for 
  66. footers and headers around them. (Older nroff -man macros always 
  67. put in page breaks, but lately some vendors have realized that 
  68. printout are made through troff, whereas nroff -man is used to 
  69. format pages for reading on screen, and so have eliminated page 
  70. breaks.) \fIRosettaMan \fR usually gets this right even without 
  71. this flag. 
  72. .TP 15
  73. -T 
  74. Turn on aggressive table parsing. 
  75. .SH "NOTES ON FILTER TYPES "
  76. .SS "ROFF "
  77. Some flavors of UNIX ship without [tn]roff source, making one's 
  78. laser printer, for man pages, little more than a laser line printer. 
  79. This filer tries to intuit the original [tn]roff directives, 
  80. which can then be recompiled by [tn]roff. 
  81. .SS "TkMan "
  82. TkMan, a hypertext man page browser, uses \fIRosettaMan \fR to 
  83. show man pages without the (usually) useless headers and footers 
  84. on each pages. It also collects section and (optionally) subsection 
  85. heads for direct access from a pulldown menu. TkMan and Tcl/Tk, 
  86. the toolkit in which it's written, are available via anonymous 
  87. ftp from \fIftp.cs.berkeley.edu \fR in the directories \fI/ucb/people/phelps/tcltk \fR
  88. and \fI/ucb/tcl \fR. 
  89. .SS "Ensemble "
  90. Ensemble, a multimedia editor of structured documents, is currently 
  91. being developed by the research groups of Professors Michael 
  92. A. Harrison and Susan L. Graham at the University of California, 
  93. Berkeley. With proper structure and presentation specifications (schemas), 
  94. the appearance of a manual page can be radically transformed 
  95. by Ensemble. 
  96. .SS "ASCII "
  97. When printed on a line printer, man pages try to produce special 
  98. text effects by overstriking characters with themselves (to produce 
  99. bold) and underscores (underlining). Other text processing software, 
  100. such as text editors, searchers, and indexers, must counteract 
  101. this. The ASCII filter strips away this formatting. Piping nroff 
  102. output through \fIcol -b \fR also strips away this formatting, 
  103. but it leaves behind unsightly page headers and footers. 
  104. .SS "Sections "
  105. Dumps section and (optionally) subsection titles. 
  106. .SS "HTML "
  107. With a simple extention to an HTTP server for Mosaic or other 
  108. World Wide Web browser, \fIRosettaMan \fR can produce high quality 
  109. HTML on the fly. Several such extensions and pointers to several 
  110. others are included in \fIRosettaMan \fR's \fIcontrib \fR directory. 
  111. .SS "SGML "
  112. I just discovered the Davenport DTD, and support for it will 
  113. be coming Real Soon Now. 
  114. .SS "LaTeX "
  115. Why not? 
  116. .SS "RTF "
  117. Use output on Mac or NeXT or whatever. Maybe take random man 
  118. pages and integrate with NeXT's documentation system better. 
  119. Maybe NeXT has own man page macros that do this. To produce PostScript, 
  120. use groff or psroff. To produce FrameMaker MIF, use FrameMaker's 
  121. builtin filter. In both cases you need [tn]roff source, so if 
  122. you only have a formatted version of the manual page, use \fI
  123. RosettaMan \fR's roff filter first. 
  124. .SH "EXAMPLES "
  125. To convert the \fIformatted \fR man page named \fIls.1 \fR back 
  126. into [tn]roff source form: \fIrman -f roff /usr/local/man/cat1/ls.1 > /usr/local/man/man1/ls.1 \fR
  127. \.br
  128. .PP
  129. Long man pages are often compressed to conserve space (compression 
  130. is especially effective on formatted man pages as many of the 
  131. characters are spaces). As it is a long man page, it probably 
  132. has subsections, which we try to separate out (some macro sets 
  133. don't distinguish subsections well enough for \fIRosettaMan \fR
  134. to detect them). Let's convert this to LaTeX format: 
  135. \.br
  136. \fIpcat /usr/catman/a_man/cat1/automount.z | rman -b -n automount -s 1 -f 
  137. latex > automount.man \fR
  138. \.br
  139. .PP
  140. Alternatively, \fIman 1 automount | rman -b -n automount -s 1 -f 
  141. latex > automount.man \fR
  142. \.br
  143. .PP
  144. For HTML/Mosaic users, \fIRosettaMan \fR can, without modification 
  145. of the source code, produce HTML links that point to other HTML 
  146. man pages either pregenerated or generated on the fly. First 
  147. let's assume pregenerated HTML versions of man pages stored in \fI/usr/man/html \fR. 
  148. Generate these one-by-one with the following form: 
  149. \.br
  150. \fIrman -f html -r 'http:/usr/man/html/%s.%s.html' /usr/man/cat1/ls.1 > /usr/man/html/ls.1.html \fR
  151. \.br
  152. .PP
  153. If you've extended your HTML client to generate HTML on the fly 
  154. you should use something like: 
  155. \.br
  156. \fIrman -f html -r 'http:~/bin/man2html?%s:%s' /usr/man/cat1/ls.1 \fR
  157. \.br
  158. when generating HTML. 
  159. .SH "BUGS/INCOMPATIBILITIES "
  160. \fIRosettaMan \fR is not perfect in all cases, but it usually 
  161. does a good job, and in any case reduces the problem of converting 
  162. man pages to light editing. 
  163. .PP
  164. Tables, especially H-P's, aren't handled very well; fortunately, 
  165. tables seem to be rare in man pages. 
  166. .PP
  167. The man pager \fIwoman \fR applies its own idea of formatting 
  168. for man pages, which can confuse \fIRosettaMan \fR. Bypass \fI
  169. woman \fR by passing the formatted manual page text directly 
  170. into \fIRosettaMan \fR. 
  171. .PP
  172. The [tn]roff output format uses \\fB to turn on boldface. If 
  173. your macro set requires .B, you'll have to a postprocess the \fI
  174. RosettaMan \fR output. 
  175. .SH "SEE ALSO "
  176. \fItkman(1) \fR, \fIxman(1) \fR, \fIman(1) \fR, \fIman(7) \fR
  177. .SH "COPYRIGHT "
  178. RosettaMan 
  179. \.br
  180. Copyright (c) 1993-1994 T.A. Phelps ( \fIphelps@CS.Berkeley.EDU \fR) 
  181. \.br
  182. All Rights Reserved. 
  183. .PP
  184. Permission to use, copy, modify, and distribute this software 
  185. and its documentation for educational, research and non-profit 
  186. purposes, without fee, and without a written agreement is hereby 
  187. granted, provided that the above copyright notice and the following 
  188. paragraph appears in all copies. 
  189. .PP
  190. Permission to incorporate this software into commercial products 
  191. may be obtained from the Office of Technology Licensing, 2150 
  192. Shattuck Avenue, Suite 510, Berkeley, CA 94704. 
  193. .PP
  194. Manual page last updated on $Date: 1994/12/07 01:09:08 $ 
  195.